

    \filetitle{filter}{Kalman smoother and estimator of out-of-likelihood parameters}{model/filter}

	\paragraph{Syntax}

Input arguments marked with a \texttt{\textasciitilde{}} (tilde) sign
may be omitted.

\begin{verbatim}
[M,Outp,V,Delta,PE,SCov] = filter(M,Inp,Range,~J,...)
\end{verbatim}

\paragraph{Input arguments}

\begin{itemize}
\item
  \texttt{M} {[} model {]} - Solved model object.
\item
  \texttt{Inp} {[} struct \textbar{} cell {]} - Input database from
  which observations for measurement variables will be taken.
\item
  \texttt{Range} {[} numeric \textbar{} char {]} - Date range on which
  the Kalman filter will be run.
\item
  \texttt{\textasciitilde{}J} {[} struct \textbar{} \emph{empty} {]} -
  Database with user-supplied time-varying paths for std deviation, corr
  coefficients, or medians for shocks; \texttt{\textasciitilde{}J} is
  equivalent to using the option
  \texttt{\textquotesingle{}vary=\textquotesingle{}}, and may be
  omitted.
\end{itemize}

\paragraph{Output arguments}

\begin{itemize}
\item
  \texttt{M} {[} model {]} - Model object with updates of std devs (if
  \texttt{\textquotesingle{}relative=\textquotesingle{}} is true) and/or
  updates of out-of-likelihood parameters (if
  \texttt{\textquotesingle{}outoflik=\textquotesingle{}} is non-empty).
\item
  \texttt{Outp} {[} struct \textbar{} cell {]} - Output struct with
  smoother or prediction data.
\item
  \texttt{V} {[} numeric {]} - Estimated variance scale factor if the
  \texttt{\textquotesingle{}relative=\textquotesingle{}} options is
  true; otherwise \texttt{V} is 1.
\item
  \texttt{Delta} {[} struct {]} - Database with estimates of
  out-of-likelihood parameters.
\item
  \texttt{PE} {[} struct {]} - Database with prediction errors for
  measurement variables.
\item
  \texttt{SCov} {[} numeric {]} - Sample covariance matrix of smoothed
  shocks; the covariance matrix is computed using shock estimates in
  periods that are included in the option
  \texttt{\textquotesingle{}objrange=\textquotesingle{}} and, at the
  same time, contain at least one observation of measurement variables.
\end{itemize}

\paragraph{Options}

\begin{itemize}
\item
  \texttt{\textquotesingle{}ahead=\textquotesingle{}} {[} numeric
  \textbar{} \emph{\texttt{1}} {]} - Predictions will be computed this
  number of period ahead.
\item
  \texttt{\textquotesingle{}chkFmse=\textquotesingle{}} {[}
  \texttt{true} \textbar{} \emph{\texttt{false}} {]} - Check the
  condition number of the forecast MSE matrix in each step of the Kalman
  filter, and return immediately if the matrix is ill-conditioned; see
  also the option
  \texttt{\textquotesingle{}fmseCondTol=\textquotesingle{}}.
\item
  \texttt{\textquotesingle{}condition=\textquotesingle{}} {[} char
  \textbar{} cellstr \textbar{} \emph{empty} {]} - List of conditioning
  measurement variables. Condition time t\textbar{}t-1 prediction errors
  (that enter the likelihood function) on time t observations of these
  measurement variables.
\item
  \texttt{\textquotesingle{}deviation=\textquotesingle{}} {[}
  \texttt{true} \textbar{} \emph{\texttt{false}} {]} - Treat input and
  output data as deviations from balanced-growth path.
\item
  \texttt{\textquotesingle{}dtrends=\textquotesingle{}} {[}
  \emph{\texttt{@auto}} \textbar{} \texttt{true} \textbar{}
  \texttt{false} {]} - Measurement data contain deterministic trends.
\item
  \texttt{\textquotesingle{}output=\textquotesingle{}} {[}
  \texttt{\textquotesingle{}predict\textquotesingle{}} \textbar{}
  \texttt{\textquotesingle{}filter\textquotesingle{}} \textbar{}
  \emph{\texttt{\textquotesingle{}smooth\textquotesingle{}}} {]} -
  Return smoother data or filtered data or prediction data or any
  combination of them.
\item
  \texttt{\textquotesingle{}fmseCondTol=\textquotesingle{}} {[}
  \emph{\texttt{eps()}} \textbar{} numeric {]} - Tolerance for the FMSE
  condition number test; not used unless
  \texttt{\textquotesingle{}chkFmse=\textquotesingle{}\ true}.
\item
  \texttt{\textquotesingle{}initCond=\textquotesingle{}} {[}
  \texttt{\textquotesingle{}fixed\textquotesingle{}} \textbar{}
  \texttt{\textquotesingle{}optimal\textquotesingle{}} \textbar{}
  \emph{\texttt{\textquotesingle{}stochastic\textquotesingle{}}}
  \textbar{} struct {]} - Method or data to initialise the Kalman
  filter; user-supplied initial condition must be a mean database or a
  mean-MSE struct.
\item
  \texttt{\textquotesingle{}lastSmooth=\textquotesingle{}} {[} numeric
  \textbar{} \emph{\texttt{Inf}} {]} - Last date up to which to smooth
  data backward from the end of the range; if \texttt{Inf} smoother will
  run on the entire range.
\item
  \texttt{\textquotesingle{}meanOnly=\textquotesingle{}} {[}
  \texttt{true} \textbar{} \emph{\texttt{false}} {]} - Return a plain
  database with mean data only; this option overrides the
  \texttt{\textquotesingle{}return*=\textquotesingle{}} options, i.e.
  \texttt{\textquotesingle{}returnCont=\textquotesingle{}},
  \texttt{\textquotesingle{}returnMse=\textquotesingle{}},
  \texttt{\textquotesingle{}returnStd=\textquotesingle{}}.
\item
  \texttt{\textquotesingle{}outOfLik=\textquotesingle{}} {[} cellstr
  \textbar{} empty {]} - List of parameters in deterministic trends that
  will be estimated by concentrating them out of the likelihood
  function.
\item
  \texttt{\textquotesingle{}objFunc=\textquotesingle{}} {[}
  \emph{\texttt{\textquotesingle{}-loglik\textquotesingle{}}} \textbar{}
  \texttt{\textquotesingle{}prederr\textquotesingle{}} {]} - Objective
  function computed; can be either minus the log likelihood function or
  weighted sum of prediction errors.
\item
  \texttt{\textquotesingle{}objRange=\textquotesingle{}} {[} numeric
  \textbar{} \emph{\texttt{Inf}} {]} - The objective function will be
  computed on the specified range only; \texttt{Inf} means the entire
  filter range.
\item
  \texttt{\textquotesingle{}precision=\textquotesingle{}} {[}
  \emph{\texttt{\textquotesingle{}double\textquotesingle{}}} \textbar{}
  \texttt{\textquotesingle{}single\textquotesingle{}} {]} - Numeric
  precision to which output data will be stored; all calculations
  themselves always run to double precision.
\item
  \texttt{\textquotesingle{}relative=\textquotesingle{}} {[}
  \emph{\texttt{true}} \textbar{} \texttt{false} {]} - Std devs of
  shocks assigned in the model object will be treated as relative std
  devs, and a common variance scale factor will be estimated.
\item
  \texttt{\textquotesingle{}returnCont=\textquotesingle{}} {[}
  \texttt{true} \textbar{} \emph{\texttt{false}} {]} - Return
  contributions of prediction errors in measurement variables to the
  estimates of all variables and shocks.
\item
  \texttt{\textquotesingle{}returnMse=\textquotesingle{}} {[}
  \emph{\texttt{true}} \textbar{} \texttt{false} {]} - Return MSE
  matrices for predetermined state variables; these can be used for
  settin up initial condition in subsequent call to another
  \texttt{filter} or \texttt{jforecast}.
\item
  \texttt{\textquotesingle{}returnStd=\textquotesingle{}} {[}
  \emph{\texttt{true}} \textbar{} \texttt{false} {]} - Return database
  with std devs of model variables.
\item
  \texttt{\textquotesingle{}weighting=\textquotesingle{}} {[} numeric
  \textbar{} \emph{empty} {]} - Weighting vector or matrix for
  prediction errors when
  \texttt{\textquotesingle{}objective=\textquotesingle{}\ \textquotesingle{}prederr\textquotesingle{}};
  empty means prediction errors are weighted equally.
\end{itemize}

\paragraph{Options for models with nonlinear equations simulated in
prediction
step}

\begin{itemize}
\tightlist
\item
  \texttt{\textquotesingle{}simulate=\textquotesingle{}} {[}
  \emph{\texttt{false}} \textbar{} cell {]} - Use the backend algorithms
  from the \href{model/simulate}{\texttt{simulate}} function to run
  nonlinear simulation for each prediction step; specify options that
  will be passed into \texttt{simulate} when running a prediction step.
\end{itemize}

\paragraph{Description}

The \texttt{\textquotesingle{}ahead=\textquotesingle{}} and
\texttt{\textquotesingle{}rollback=\textquotesingle{}} options cannot be
combined with one another, or with multiple data sets, or with multiple
parameterisations.

\subparagraph{Initial conditions in time
domain}

By default (with
\texttt{\textquotesingle{}initCond=\textquotesingle{}\ \textquotesingle{}stochastic\textquotesingle{}}),
the Kalman filter starts from the model-implied asymptotic distribution.
You can change this behaviour by setting the option
\texttt{\textquotesingle{}initCond=\textquotesingle{}} to one of the
following four different values:

\begin{itemize}
\item
  \texttt{\textquotesingle{}fixed\textquotesingle{}} -- the filter
  starts from the model-implied asymptotic mean (steady state) but with
  no initial uncertainty. The initial condition is treated as a vector
  of fixed, non-stochastic, numbers.
\item
  \texttt{\textquotesingle{}optimal\textquotesingle{}} -- the filter
  starts from a vector of fixed numbers that is estimated optimally
  (likelihood maximising).
\item
  database (i.e.~struct with fields for individual model variables) -- a
  database through which you supply the mean for all the required
  initial conditions, see help on \href{model/get}{\texttt{model/get}}
  for how to view the list of required initial conditions.
\item
  mean-mse struct (i.e.~struct with fields \texttt{.mean} and
  \texttt{.mse}) -- a struct through which you supply the mean and MSE
  for all the required initial conditions.
\end{itemize}

\subparagraph{Contributions of measurement variables to the estimates of
all
variables}

Use the option
\texttt{\textquotesingle{}returnCont=\textquotesingle{}\ true} to
request the decomposition of measurement variables, transition
variables, and shocks into the contributions of each individual
measurement variable. The resulting output database will include one
extra subdatabase called \texttt{.cont}. In the \texttt{.cont}
subdatabase, each time series will have Ny columns where Ny is the
number of measurement variables in the model. The k-th column will be
the contribution of the observations on the k-th measurement variable.

The contributions are additive for linearised variables, and
multiplicative for log-linearised variables (log variables). The
difference between the actual path for a particular variable and the sum
of the contributions (or their product in the case of log varibles) is
due to the effect of constant terms and deterministic trends.

\paragraph{Example}


